<!--
Copyright (c) 2000, 2001, 2002, 2003, 2004, 2005, 2008, 2009, 2013
	The President and Fellows of Harvard College.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. Neither the name of the University nor the names of its contributors
   may be used to endorse or promote products derived from this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE UNIVERSITY AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE UNIVERSITY OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
-->
<html>
<head>
<title>sbrk</title>
<link rel="stylesheet" type="text/css" media="all" href="../man.css">
</head>
<body bgcolor=#ffffff>
<h2 align=center>sbrk</h2>
<h4 align=center>OS/161 Reference Manual</h4>

<h3>Name</h3>
<p>
sbrk - set process break (allocate memory)
</p>

<h3>Library</h3>
<p>
Standard C Library (libc, -lc)
</p>

<h3>Synopsis</h3>
<p>
<tt>#include &lt;unistd.h&gt;</tt><br>
<br>
<tt>void *</tt><br>
<tt>sbrk(intptr_t </tt><em>amount</em><tt>);</tt>
</p>

<h3>Description</h3>
<p>
The "break" is the end address of a process's heap region. The
<tt>sbrk</tt> call adjusts the "break" by the amount <em>amount</em>.
It returns the old "break". Thus, to determine the current "break",
call <tt>sbrk(0)</tt>.
</p>

<p>
The heap region is initially empty, so at process startup, the
beginning of the heap region is the same as the end and may thus be
retrieved using sbrk(0).
</p>

<p>
In OS/161, the initial "break" must be page-aligned, and <tt>sbrk</tt>
only need support values of <em>amount</em> that result in
page-aligned "break" addresses. Other values of <em>amount</em> may be
rejected. This may simplify the implementation. You may place the
heap wherever you like in a process's address space (though obviously
not on top of something else) and it need not appear at the same
location in every process.
</p>

<p>
Traditionally, the initial "break" is specifically defined to be the
end of the BSS (uninitialized data) region, and traditionally any
<em>amount</em>, page-aligned or not, may legally be used with
<tt>sbrk</tt>.
</p>

<p>
Ordinarily, user-level code should call
<A HREF=../libc/malloc.html>malloc</A> for memory allocation. The
<tt>sbrk</tt> interface is intended only to be the back-end interface
for <tt>malloc</tt>. Mixing calls to <tt>malloc</tt> and <tt>sbrk</tt>
will likely confuse <tt>malloc</tt> and produces undefined behavior.
</p>

<p>
While one can lower the "break" by passing negative values of
<em>amount</em>, one may not set the end of the heap to an address
lower than the beginning of the heap. Attempts to do so must be
rejected.
</p>

<p>
The call (like all system calls) should be atomic. In this case, that
means that if you have a multithreaded process, simultaneous calls to
<tt>sbrk</tt> from different threads should not interfere with each
other and should update the "break" state atomically.
</p>

<h3>Return Values</h3>
<p>
On success, <tt>sbrk</tt> returns the previous value of the "break".
On error, ((void *)-1) is returned, and <A HREF=errno.html>errno</A>
is set according to the error encountered.
</p>

<h3>Errors</h3>
<p>
The following error codes should be returned under the conditions
given. Other error codes may be returned for other cases not
mentioned here.

<table width=90%>
<tr><td width=5% rowspan=2>&nbsp;</td>
    <td with=10% valign=top>ENOMEM</td>
			<td>Sufficient virtual memory to satisfy the
				request was not available, or the
				process has reached the limit of the
				memory it is allowed to allocate.</td></tr>
<tr><td valign=top>EINVAL</td>
			<td>The request would move the "break" below
				its initial value.</td></tr>
</table>
</p>

<h3>Restrictions</h3>
<p>
While you can return pages that happen to be at the end of the heap to
the system, there is no way to use the <tt>sbrk</tt> interface to
return unused pages in the middle of the heap. If you wish to do this,
you will need to design a new or supplemental interface.
</p>

</body>
</html>
